home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1995 August: Tool Chest / Dev.CD Aug 95 TC / Dev.CD Aug 95 TC.toast / Tool Chest / Interfaces / UniversalInterfaces 2.1B1 / AIncludes / Translation.a < prev    next >
Encoding:
Text File  |  1995-04-18  |  12.0 KB  |  342 lines  |  [TEXT/MPS ]
  1. ;
  2. ;    File:        Translation.a
  3. ;
  4. ;    Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5. ;
  6. ;    Version:    Technology:    Macintosh Easy Open 1.1
  7. ;                Package:    Universal Interfaces 2.1ß1 in “MPW Prerelease” on ETO #17
  8. ;
  9. ;    Copyright:    © 1984-1995 by Apple Computer, Inc.
  10. ;                All rights reserved.
  11. ;
  12. ;    Bugs?:        If you find a problem with this file, use the Apple Bug Reporter
  13. ;                stack.  Include the file and version information (from above)
  14. ;                in the problem description and send to:
  15. ;                    Internet:    apple.bugs@applelink.apple.com
  16. ;                    AppleLink:    APPLE.BUGS
  17. ;
  18. ;
  19.  
  20.     IF &TYPE('__TRANSLATION__') = 'UNDEFINED' THEN
  21. __TRANSLATION__ SET 1
  22.  
  23.  
  24.     IF &TYPE('__TYPES__') = 'UNDEFINED' THEN
  25.     include 'Types.a'
  26.     ENDIF
  27. ;        include 'ConditionalMacros.a'                                ;
  28.  
  29.     IF &TYPE('__FILES__') = 'UNDEFINED' THEN
  30.     include 'Files.a'
  31.     ENDIF
  32. ;        include 'MixedMode.a'                                        ;
  33. ;        include 'OSUtils.a'                                        ;
  34. ;            include 'Memory.a'                                        ;
  35.  
  36.     IF &TYPE('__COMPONENTS__') = 'UNDEFINED' THEN
  37.     include 'Components.a'
  38.     ENDIF
  39.  
  40.     IF &TYPE('__TRANSLATIONEXTENSIONS__') = 'UNDEFINED' THEN
  41.     include 'TranslationExtensions.a'
  42.     ENDIF
  43. ;        include 'Quickdraw.a'                                        ;
  44. ;            include 'QuickdrawText.a'                                ;
  45. ; typedef short             DocOpenMethod
  46.  
  47. domCannot                        EQU        0
  48. domNative                        EQU        1
  49. domTranslateFirst                EQU        2
  50. domWildcard                        EQU        3
  51.  
  52. ; 0L terminated array of OSTypes, or FileTypes
  53. ; typedef OSType             TypesBlock[64]
  54. ; typedef OSType             *TypesBlockPtr
  55. ; Progress dialog resource ID
  56.  
  57. kTranslationScrapProgressDialogID EQU        -16555
  58.  
  59. ; block of data that describes how to translate
  60. FileTranslationSpec     RECORD    0
  61. componentSignature         ds.l   1        ; offset: $0 (0)
  62. translationSystemInfo     ds.l   1        ; offset: $4 (4)
  63. src                         ds     FileTypeSpec ; offset: $8 (8)
  64. dst                         ds     FileTypeSpec ; offset: $1C (28)
  65. sizeof                     EQU *            ; size:   $30 (48)
  66.                         ENDR
  67.  
  68. ; typedef struct FileTranslationSpec  FileTranslationSpec
  69. ; typedef FileTranslationSpec  *FileTranslationSpecArrayPtr
  70. ;****************************************************************************************
  71. ;* 
  72. ;*   GetFileTypesThatAppCanNativelyOpen
  73. ;* 
  74. ;*  This routine returns a list of all FileTypes that an application can open by itself
  75. ;* 
  76. ;*  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  77. ;*             appSignature        signature (creator) of application
  78. ;*             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  79. ;* 
  80. ;*  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  81. ;
  82. ;
  83. ; pascal OSErr GetFileTypesThatAppCanNativelyOpen(short appVRefNumHint, OSType appSignature, FileType *nativeTypes)
  84. ;
  85.     IF ¬ GENERATINGCFM THEN
  86.         Macro
  87.         _GetFileTypesThatAppCanNativelyOpen
  88.             moveq    #28,d0
  89.             dc.w     $ABFC
  90.         EndM
  91.     ELSE
  92.         IMPORT_CFM_FUNCTION    GetFileTypesThatAppCanNativelyOpen
  93.     ENDIF
  94.  
  95. ;****************************************************************************************
  96. ;* 
  97. ;*  ExtendFileTypeList
  98. ;* 
  99. ;*  This routine makes a new list of file types that can be translated into a type in the given list
  100. ;*  Used by StandardFile
  101. ;* 
  102. ;*  Enter:    originalTypeList        pointer to list of file types that can be opened
  103. ;*             numberOriginalTypes        number of file types in orgTypeList
  104. ;*              extendedTypeList        pointer to a buffer to be filled with file types
  105. ;*             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  106. ;* 
  107. ;*  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  108. ;*             numberExtendedTypes        number of file types put in extendedTypeList
  109. ;
  110. ;
  111. ; pascal OSErr ExtendFileTypeList(const FileType *originalTypeList, short numberOriginalTypes, FileType *extendedTypeList, short *numberExtendedTypes)
  112. ;
  113.     IF ¬ GENERATINGCFM THEN
  114.         Macro
  115.         _ExtendFileTypeList
  116.             moveq    #9,d0
  117.             dc.w     $ABFC
  118.         EndM
  119.     ELSE
  120.         IMPORT_CFM_FUNCTION    ExtendFileTypeList
  121.     ENDIF
  122.  
  123. ;****************************************************************************************
  124. ;* 
  125. ;* 
  126. ;*  This routine checks if a file can be opened by a particular application.
  127. ;*  If so, it returns if it needs to be translated first, and if so then how.
  128. ;*  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  129. ;*  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  130. ;* 
  131. ;*  Enter:    targetDocument        document to check if it can be opened
  132. ;*             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  133. ;*             appSignature        signature (creator) of application to open doc
  134. ;*             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  135. ;*             onlyNative            whether to consider if document can be translated before opening
  136. ;*             howToOpen            pointer to buffer in which to put how the document can be opened
  137. ;*             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  138. ;* 
  139. ;*  Exit:    howToOpen            whether file needs to be translated to be read
  140. ;*             howToTranslate        if file can be translated, buffer filled in with how to translate
  141. ;*             returns                noErr, noPrefAppErr
  142. ;
  143. ;
  144. ; pascal OSErr CanDocBeOpened(const FSSpec *targetDocument, short appVRefNumHint, OSType appSignature, const FileType *nativeTypes, Boolean onlyNative, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  145. ;
  146.     IF ¬ GENERATINGCFM THEN
  147.         Macro
  148.         _CanDocBeOpened
  149.             moveq    #30,d0
  150.             dc.w     $ABFC
  151.         EndM
  152.     ELSE
  153.         IMPORT_CFM_FUNCTION    CanDocBeOpened
  154.     ENDIF
  155.  
  156. ;****************************************************************************************
  157. ;* 
  158. ;*  GetFileTranslationPaths
  159. ;* 
  160. ;*  This routine returns a list of all ways a translation can occure to or from a FileType.
  161. ;*  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  162. ;* 
  163. ;*  Enter:    srcDoc            source file or NULL for all matches
  164. ;*             dstDoc            destination FileType or NULL for all matches
  165. ;*             maxResultCount
  166. ;*             resultBuffer
  167. ;*  Exit:    number of paths
  168. ;
  169. ;
  170. ; pascal short GetFileTranslationPaths(FSSpec *srcDocument, FileType dstDocType, unsigned short maxResultCount, FileTranslationSpecArrayPtr resultBuffer)
  171. ;
  172.     IF ¬ GENERATINGCFM THEN
  173.         Macro
  174.         _GetFileTranslationPaths
  175.             moveq    #56,d0
  176.             dc.w     $ABFC
  177.         EndM
  178.     ELSE
  179.         IMPORT_CFM_FUNCTION    GetFileTranslationPaths
  180.     ENDIF
  181.  
  182. ;****************************************************************************************
  183. ;* 
  184. ;*  GetPathFromTranslationDialog
  185. ;* 
  186. ;*  This routine, with a given document, application, and a passed typelist will display the
  187. ;*  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  188. ;*  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  189. ;*  The routine returns the translation path information.
  190. ;* 
  191. ;*  Enter:    theDocument            FSSpec to document to open
  192. ;*             theApplication        FSSpec to application to open document
  193. ;*             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  194. ;*                                 you would like the documented translated to.  Order most perferred
  195. ;*                                 to least.
  196. ;* 
  197. ;*  Exit:    howToOpen            Translation method needed to open document
  198. ;*             howToTranslate        Translation specification
  199. ;*             returns                Any errors that might occur.
  200. ;
  201. ;
  202. ; pascal OSErr GetPathFromTranslationDialog(const FSSpec *theDocument, const FSSpec *theApplication, TypesBlockPtr typeList, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  203. ;
  204.     IF ¬ GENERATINGCFM THEN
  205.         Macro
  206.         _GetPathFromTranslationDialog
  207.             moveq    #55,d0
  208.             dc.w     $ABFC
  209.         EndM
  210.     ELSE
  211.         IMPORT_CFM_FUNCTION    GetPathFromTranslationDialog
  212.     ENDIF
  213.  
  214. ;****************************************************************************************
  215. ;* 
  216. ;*   TranslateFile
  217. ;* 
  218. ;*  This routine reads a file of one format and writes it to another file in another format. 
  219. ;*  The information on how to translated is generated by the routine CanDocBeOpened.
  220. ;*  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  221. ;*  The destination file must not exist.  It is created by this routine.  
  222. ;* 
  223. ;*  Enter:    sourceDocument            input file to translate
  224. ;*             destinationDocument        output file of translation
  225. ;*             howToTranslate            pointer to info on how to translate
  226. ;*  Exit:    returns                    noErr, badTranslationSpecErr 
  227. ;
  228. ;
  229. ; pascal OSErr TranslateFile(const FSSpec *sourceDocument, const FSSpec *destinationDocument, const FileTranslationSpec *howToTranslate)
  230. ;
  231.     IF ¬ GENERATINGCFM THEN
  232.         Macro
  233.         _TranslateFile
  234.             moveq    #12,d0
  235.             dc.w     $ABFC
  236.         EndM
  237.     ELSE
  238.         IMPORT_CFM_FUNCTION    TranslateFile
  239.     ENDIF
  240.  
  241. ;****************************************************************************************
  242. ;* 
  243. ;*   GetDocumentKindString
  244. ;* 
  245. ;*  This routine returns the string the Finder should show for the "kind" of a document
  246. ;*  in the GetInfo window and in the kind column of a list view.  
  247. ;* 
  248. ;*  Enter:    docVRefNum        The volume containing the document
  249. ;*             docType            The catInfo.fdType of the document
  250. ;*             docCreator        The catInfo.fdCreator of the document
  251. ;*             kindString        pointer to where to return the string
  252. ;* 
  253. ;*  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  254. ;*             returns            noErr, or afpItemNoFound if kind could not be determined
  255. ;
  256. ;
  257. ; pascal OSErr GetDocumentKindString(short docVRefNum, OSType docType, OSType docCreator, Str63 kindString)
  258. ;
  259.     IF ¬ GENERATINGCFM THEN
  260.         Macro
  261.         _GetDocumentKindString
  262.             moveq    #22,d0
  263.             dc.w     $ABFC
  264.         EndM
  265.     ELSE
  266.         IMPORT_CFM_FUNCTION    GetDocumentKindString
  267.     ENDIF
  268.  
  269. ;****************************************************************************************
  270. ;* 
  271. ;*  GetTranslationExtensionName
  272. ;* 
  273. ;*  This routine returns the translation system name from a specified TranslationSpec
  274. ;* 
  275. ;*  Enter:    translationMethod    The translation path to get the translation name from
  276. ;* 
  277. ;*  Exit:    extensionName        The name of the translation system
  278. ;*             returns                Any errors that might occur
  279. ;
  280. ;
  281. ; pascal OSErr GetTranslationExtensionName(const FileTranslationSpec *translationMethod, Str31 extensionName)
  282. ;
  283.     IF ¬ GENERATINGCFM THEN
  284.         Macro
  285.         _GetTranslationExtensionName
  286.             moveq    #54,d0
  287.             dc.w     $ABFC
  288.         EndM
  289.     ELSE
  290.         IMPORT_CFM_FUNCTION    GetTranslationExtensionName
  291.     ENDIF
  292.  
  293. ;****************************************************************************************
  294. ;* 
  295. ;*  GetScrapDataProcPtr
  296. ;* 
  297. ;*  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  298. ;*  get the data to be translated.  The first call TranslateScrap will make to this is to
  299. ;*  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  300. ;*  with a list all the formats that you have available to be translated, and the length of each.
  301. ;*  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  302. ;*  the formats that 'fmts' list said was available.
  303. ;* 
  304. ;*  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  305. ;*             dataH                    Handle in which to put the requested data
  306. ;*             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  307. ;*             
  308. ;*  Exit:    dataH                    Handle is resized and filled with data in requested format
  309. ;
  310. ; typedef GetScrapDataUPP     GetScrapData
  311. ;****************************************************************************************
  312. ;* 
  313. ;*  TranslateScrap
  314. ;* 
  315. ;*  This routine resizes the destination handle and fills it with data of the requested format.
  316. ;*  The data is generated by translated one or more source formats of data supplied by
  317. ;*  the procedure srcDataGetter.  
  318. ;*  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  319. ;*  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  320. ;* 
  321. ;*  Enter:    sourceDataGetter            Pointer to routine that can get src data
  322. ;*             sourceDataGetterRefCon        Extra parameter for dataGetter
  323. ;*             destinationFormat            Format of data desired
  324. ;*             destinationData                Handle in which to store translated data
  325. ;*             
  326. ;*  Exit:    dstData                        Handle is resized and filled with data in requested format
  327. ;
  328. ;
  329. ; pascal OSErr TranslateScrap(GetScrapData sourceDataGetter, void *sourceDataGetterRefCon, ScrapType destinationFormat, Handle destinationData, short progressDialogID)
  330. ;
  331.     IF ¬ GENERATINGCFM THEN
  332.         Macro
  333.         _TranslateScrap
  334.             moveq    #14,d0
  335.             dc.w     $ABFC
  336.         EndM
  337.     ELSE
  338.         IMPORT_CFM_FUNCTION    TranslateScrap
  339.     ENDIF
  340.  
  341.     ENDIF ; __TRANSLATION__
  342.